코덱스 로컬특화 코딩에이전트 (NDX) — EP1 에이전트 만들고 테트리스 생성

OpenAI Codex 오픈소스를 TypeScript로 재구현한 NDX 에이전트를, 클라우드가 아닌 로컬 LLM 위에서 돌려 토큰 비용 없이 코드를 생성하는 환경을 구축합니다.

0. 사전 필수 용어 (선행지식)

1. 코딩 에이전트 — 자연어 지시를 받아 코드를 작성·실행·수정하는 AI 도구입니다(예: OpenAI Codex). 본 강의는 이를 로컬 모델로 돌립니다.
2. 로컬 LLM — 클라우드가 아닌 내 기기에서 실행하는 언어 모델입니다. LM Studio로 띄웁니다(§4 Step 1).
3. 양자화(quantization) — 모델 가중치 정밀도를 낮춰(2/3/4비트) 파일·메모리를 줄이는 기법입니다. 로컬 실행의 핵심(§4 Step 2, §9).
4. KV 캐시(KV Cache) — 토큰 생성 시 반복 참조하는 메모리입니다. GPU에 올리면 속도가 크게 오릅니다(§6 핵심 원리).
5. MoE(Mixture of Experts) — 입력마다 일부 전문가 레이어만 활성화하는 구조입니다. Offload FFN to RAM으로 VRAM을 아낍니다.
6. Docker — OS 제약 없이 동일한 리눅스 환경을 컨테이너로 재현하는 도구입니다(§4 Step 4).

📚 참고: 로컬 추론 기초는 LM Studio·llama.cpp(github.com/ggml-org/llama.cpp) 문서를 함께 보세요.

1. 주제 정의

로컬특화 코딩 에이전트(Local-Specialized Coding Agent)는 로컬 LLM의 약점(작은 추론력·컨텍스트)을 에이전트 설계로 보완해, 로컬 환경에서도 실제로 쓸 만한 코딩 도구를 만드는 접근입니다. 본 강의의 NDX는 OpenAI Codex 오픈소스(Apache 2.0)를 TypeScript로 재구현한 예입니다.

핵심 아이디어: 모델을 더 키우는 대신, 에이전트(설정·도구·환경)를 로컬 모델에 맞춰 설계한다.

2. 풀려는 문제

• 문제 1 — 토큰 비용: 클라우드 코딩 에이전트는 사용량에 비례해 비용이 듭니다. 로컬 모델은 무료입니다.
• 문제 2 — 클라우드 전제 설계: 프론티어 에이전트는 강력한 클라우드 모델을 전제해, 로컬 모델에선 잘 동작하지 않습니다.
• 문제 3 — 로컬 속도·VRAM 한계: 로컬 LLM은 설정에 따라 속도·메모리 병목이 큽니다. 최적화가 필요합니다.

💡 실무 노하우: 로컬 에이전트의 체감 성능은 "모델 크기"보다 "KV 캐시·레이어의 GPU 배치"에서 갈립니다. 같은 모델도 설정으로 토큰/초가 몇 배 차이 납니다.

3. 핵심 개념·구조

• LM Studio (+ LM Link) — 로컬 LLM을 다운로드·실행하고 OpenAI/Anthropic 호환 API로 노출. LM Link로 여러 머신을 묶어 처리력 확장.
• NDX 에이전트 — Codex를 TS로 재구현. .ndx/settings.json 한 파일로 provider·모델·권한·검색 도구 통합.
• Docker — OS 무관 리눅스 환경에서 재현 가능하게 빌드·실행.

[NDX 에이전트 (Docker 컨테이너)]
        │  settings.json: provider=LM Studio URL
        ▼
 LM Studio 서버 (OpenAI 호환 API)
        │  (LM Link 로 여러 머신 확장 가능)
        ▼
 로컬 LLM (양자화 모델, KV 캐시는 GPU 우선)
        │
        ▼
 [코드 생성: tetris.html]

4. 구현 가이드 (Do It Yourself)

시작 전 (Before you begin)

이 섹션을 완료하면 로컬 LLM 위에서 NDX 에이전트로 간단한 코드를 생성할 수 있습니다.

선수 조건: - 충분한 GPU VRAM(예: NVIDIA 24GB+ 또는 Apple Silicon 대용량) + RAM - GitHub/Git, Docker Desktop(Compose 포함)

소요 시간: 약 40~60분(모델 다운로드 별도).

Step 1 — LM Studio + LM Link

목표: 로컬 LLM 서버를 띄웁니다.

1. LM Studio 설치 → Settings에서 LM Link 활성화(계정 로그인).
2. 여러 머신을 같은 계정으로 묶어 네트워크 확장(선택).
3. 모델 다운로드·로드 후 Server 탭에서 호환 API(OpenAI/Anthropic) 노출 확인.

✅ 확인: LM Studio가 실행되고 연결된 머신이 보입니다.

Step 2 — 양자화 모델 + KV 캐시 최적화

목표: 로컬 출력 속도를 끌어올립니다.

1. 사양에 맞는 양자화(예: Q4_K_M, MXF4P) 모델 다운로드.
2. Load 시 Context Length 최대, N-GPU Layers로 GPU 레이어 수 조정.
3. KV 캐시를 GPU에 우선 할당(속도 영향이 가장 큼).
4. MoE 모델이면 Offload FFN to RAM으로 VRAM 절약.

⚠️ 주의: Windows에서 NVIDIA 실제 사용률은 작업관리자로 부정확합니다. CUDA 추적기를 써서 VRAM/사용률을 모니터링하세요.

💡 실무 노하우: 텍스트를 넣어 토큰/초를 측정하며 N-GPU Layers를 올렸다 내렸다 하며 최적값을 찾습니다. 목표는 예: 50토큰/초 이상.

✅ 확인: 모델이 로딩되고 만족스러운 토큰/초가 나옵니다.

Step 3 — NDX 클론 + settings.json

목표: 에이전트가 로컬 모델을 쓰도록 설정합니다.

git clone https://github.com/hikaMaeng/ndx
# .ndx/settings.json 편집

.ndx/settings.json 주요 키: - provider: LM Studio URL(예 http://localhost:1234) - models: 이름·provider·컨텍스트 크기 - default_model, permissions, search_providers

💡 실무 노하우: 기존 Codex의 흩어진 설정(env·.codex·config.toml)을 한 파일로 통합 → 재현·추적이 쉬워집니다.

✅ 확인: settings.json에 provider/모델이 의도대로 들어갔습니다.

Step 4 — Docker로 NDX 실행

목표: OS 무관 재현 가능한 환경에서 에이전트를 띄웁니다.

docker-compose up --build -d   # home·workspace 볼륨 포함
docker exec -it <container> bash

📚 참고: Docker Compose 공식 github.com/docker/compose. WSL2도 좋은 대안입니다.

✅ 확인: 컨테이너가 빌드·실행되고 .ndx 설정이 적용됩니다.

Step 마지막 — 테트리스 생성

cd workspace && mkdir tetris && cd tetris
ndx
# >>> HTML로 테트리스 게임을 만들어줘

예상 결과: tetris.html이 생성되고 브라우저에서 게임이 동작합니다. (테트리스는 학습량이 많아 잘 생성되는 편.)

5. 적용 사례 (공신력 오픈소스)

• OpenAI Codex (https://github.com/openai/codex) — 본 에이전트의 원본(Apache 2.0).
• NDX (https://github.com/hikaMaeng/ndx) — 강의의 TS 재구현 로컬 특화 에이전트.
• Docker Compose (https://github.com/docker/compose) — 컨테이너 환경 재현.
• llama.cpp (https://github.com/ggml-org/llama.cpp) — 양자화 로컬 추론 엔진.
• HuggingFace Transformers (https://github.com/huggingface/transformers) — 모델·양자화 생태계.

💡 실무 노하우: 로컬 모델은 OpenAI 호환 API로 노출되므로, 기존 OpenAI SDK 코드를 base URL만 바꿔 재사용할 수 있습니다.

6. 핵심 원리

1. 에이전트가 모델 약점을 보완 — 로컬 모델의 한계를 설정·도구·흐름 설계로 메운다(모델만 키우지 않는다).
2. KV 캐시 GPU 우선 — 반복 접근 메모리를 고대역 VRAM에 두는 것이 로컬 속도의 핵심.

7. 변형·확장

• 웹 검색 도구 통합 + 검색 엔진별 파싱 규칙 외부화(search.json).
• 외부(External) 도구 인식·활용 기능 추가.
• 스킬(Skills) 이식 — Codex의 스킬 기능을 NDX로 포팅.
• 컨텍스트 사용량 명령 — LLM 메모리 상태 모니터링.

8. 다른 도구·접근과의 비교 (3-way)

• vs 클라우드 Codex/Claude Code: 클라우드는 최고 모델·관리 편의 ↔ 비용·데이터 외부 전송. 로컬 NDX는 그 반대.
• vs 직접 코딩: 직접은 완전 통제 ↔ 느림. 에이전트는 속도↑·검토 필요.
• vs Ollama 단독: Ollama는 모델 실행만. NDX는 에이전트(도구·권한·워크플로우)까지 제공.

9. 한계·트레이드오프

1. 하드웨어 요구 — 큰 모델·긴 컨텍스트는 VRAM을 많이 씀.
2. 로컬 모델 품질 — 클라우드 프론티어 대비 추론력 한계. 복잡 작업은 실패 가능.
3. 설정 복잡도 — 양자화·KV 캐시·Docker·provider 설정 학습 곡선.

10. 최신 권장 패턴 (2026-05 기준, OpenAI Codex·LM Studio 문서)

• 설정 단일화(settings.json): 재현·추적 용이.
• Docker 재현 환경: OS 무관·공유 가능.
• 양자화 + KV 캐시 GPU 우선: 로컬 속도 최적화의 표준.
• MoE offload: 대형 MoE를 제한된 VRAM에서 구동.

📚 참고: 로컬 에이전트 패턴은 github.com/openai/codex 와 github.com/hikaMaeng/ndx 에서 교차 확인하세요.

11. 메타인지 자기평가

Step 1 — 현재 상태 점검

nvidia-smi   # 또는 CUDA 추적기 — 가용 VRAM 확인

Step 2 — 적용 가능성 평가 - 가용 VRAM이 목표 양자화 모델 + KV 캐시를 담는가? - KV 캐시를 GPU에 올리도록 설정했는가? - 설정·환경이 Docker로 재현 가능한가?

Step 3 — 점진 적용 1. 작은 양자화 모델로 NDX 동작을 먼저 검증(테트리스 등 쉬운 작업). 2. 토큰/초를 측정하며 GPU 레이어·KV 캐시 설정을 튜닝. 3. 안정화 후 더 큰 모델·웹검색·스킬로 확장.